<!DOCTYPE html>
<title>CSS Scroll Snap Diff Annotations</title>
<meta charset=utf-8>
<link rel="stylesheet" href="https://www.w3.org/StyleSheets/TR/2016/W3C-UD">
<style>
html, body { background-image: none; }
.changes > dt:before {
	content: counter(changes) " ";
}
.changes > dt {
	counter-increment: changes;
	margin: 2em 0 1em;
}

dt > strong,
ins, del {
  color: inherit;
  border-radius: 0.5em;
  padding: 0 0.25em;
  background: inherit;
}
ins { background: #AFA; }
del { background: #FBB; }
.move { background: #FF0; }
.up::after { content: "⇑"; }
.down::after { content: "⇓"; }
.block { display: block; }

dt > strong {
  background: yellow;
}

th {
	text-align: right;
}
</style>
<body class="toc-inline">

<h1>CSS Scroll Snap Diff Annotations</h1>

<p>This is a list of <a href="diff">differences</a>
between the <a href="http://www.w3.org/TR/css-snappoints-1/">CSS Scroll Snap Module</a> as maintained by Matt Rakow
and the <a href="http://drafts.csswg.org/css-scroll-snap/">CSS Scroll Snap Module Change Proposal</a> maintained by Tab and fantasai.

<blockquote cite="https://www.w3.org/mid/796F6DC1-B229-41A4-A0A0-D1E1E04799C4@apple.com">
	<p>At the most recent F2F the group agreed to accept a bunch of changes from Fantasai and Tab. Microsoft asked for some time to do a final review.

	<p>While we don't have immediate plans to implement, it would be nice to get the specification stable soon. Can we set a deadline for review, after which we go ahead with the resolution from the meeting?

	<p>I'm not sure how much time is necessary. Microsoft?
	<address>Dean Jackson, www-style, 10 December 2015</address>
</blockquote>

<h2>Suggested Process</h2>

<p>In the interests of F2F time, we are requesting that the WG adopt the following rapid-decision format for resolution of these changes:

<ol>
	<li>First, a quick presentation of the change.
	<li>Second, a few minutes for people to peruse the change (if necessary),
	and to enter a straw poll in IRC:
	<table class="data">
		<tr>
			<th>+1
			<td>I agree with adopting the new wording.
		<tr>
			<th>-1
			<td>I disagree with adopting the new wording.
		<tr>
			<th>+2
			<td>I think the new wording is better than the old one,
			but I would like to see further improvements,
			which I will file as a follow-up issue.
		<tr>
			<th>0
			<td>I need more time to decide, please revisit this after the break
			(during which I promise to review the change, obviously).
		<tr>
			<th>T
			<td>I need more time to decide, please revisit this tomorrow morning
			(at which point I promise to have an opinion or a damned good reason <em>outside of my control</em> to ask for more time).
		</li>
	</table>
	Abstentions shall be recorded by omission.
	The chairs will ask by a show of hands if anyone needs another minute or two to decide, and otherwise swiftly end the poll.
	<li>If the straw poll results are reasonably conclusive,
	the chairs will record a resolution to adopt the change.
	If they are not conclusive, the chairs will open discussion.
</ol>

<p>Our goal in presenting this list is to close, by the end of the F2F,
on all outstanding technical and editorial issues,
and by formally adopting the exact wording changes necessary to resolve these issues,
remove the need for any further spec-editor discretion in updating the spec.
This will allow somebody who actually has the time (i.e. not Matt Rakow)
to make the edits
so that the spec can be 100% up-to-date by next week rather than sometime in the next six months <em>maybe</em>.

<p>(Of course, not all of these edits are perfect,
but insofar as they are better we would like the CSSWG to formally adopt them.
Further review, edits, and improvements can then be made once there is a fully up-to-date consensus spec on /TR.)


<h2>Specific Changes</h2>

<dl class="changes">
	<dt id=change-title>Title Change <strong>Merged</strong>
	<dd>
		Robert O'Callahan requested a change to the name of the spec,
		because (with his requested changes)
		it's not about snappoing points,
		but about snapping box edges.
		(<a href="issues-by-issue#issue-43">Issue 43</a> filed December 2013)
		<blockquote>
			<p>CSS Scroll Snap <del>Points</del> Module Level 1
			<p>http://www.w3.org/TR/css-<del>snappoints</del><ins>scroll-snap</ins>-1/
		</blockquote>

	<dt id=change-margin-area>Terminology Change: Scroll Snap Area <strong>Merged</strong>
	<dd>
		Tab and I introduced the term “scroll snap area”
		to refer to the rectangle being aligned within the viewport.
		Matt's version uses “scroll snap margin” to refer to this area.
		However the term “scroll snap margin” is misleading
		because the margin area of a box
		is the area inside the margin edges <em>and outside its border box</em>
		whereas the area of concern here includes the entire area of the defined rectangle.

		<pre>s/<del>scroll snap margin</del>/<ins>scroll snap area</ins>/g;</pre>

	<dt id=change-margin-border-box>Error: border-box vs. margin-box
	 <strong>Partially Merged</strong>
	<dd>
		Matt's spec parenthetically mentions that the scroll snap area defaults to the margin box. However, the spec actually defines that it defaults to the border box. This change corrects this error.

		<blockquote>
			<p>Snap positions can be specified as a particular alignment (scroll-snap-align) of an element’s scroll snap area
			(<del><code>scroll-snap-margin</code>, defaulting to its margin box</del>
			<ins>its border box, as modified by <code>scroll-snap-margin</code></ins>)
			within &hellip;
		</blockquote>

		(In the most recent changes, “margin box” has been replaced with “border box”,
		but the resulting text is awkward.)

	<dt id="change-physics">Move: Undefined Animations and Physics
	 <strong>Merged</strong>
	<dd>
		There is a statement in the definition of <code>scroll-snap-type</code>
		that, since  it applies generally to scroll-snapping,
		we felt belonged in Overview section that defines
		the overall scroll-snapping model
		rather than specifically in <code>scroll-snap-type</code>.

		<blockquote>
			<p><ins class="move"><del>It</del> <ins>The CSS Scroll Snap Module</ins> intentionally does not specify nor mandate any precise animations or physics used to enforce snap positions; this is left up to the user agent.</ins>
		</blockquote>

	<dt id=change-axes>Specifying Scroll-snap Axes
	 <strong>Partially Merged</strong>
	<dd>
		The WG <a href="https://www.w3.org/mid/CADhPm3t9_fcrr8mZ9eYzkghmkJ0pnmOK5_c10w6RAv51T-28AQ@mail.gmail.com">resolved on 2 December 2015</a>
		to specify, on a property applied to the scroll container, which axis(es) would be honored in scroll snapping.
		he following changes implement this:

		<blockquote>
			<table class="def">
				<tr>
					<th>Name:
					<td><dfn>scroll-snap-type</dfn>
				<tr>
					<th>Value
					<td>none <a href="https://drafts.csswg.org/css-values-3/#comb-one">|</a> <ins>[</ins> proximity <a href="https://drafts.csswg.org/css-values-3/#comb-one">|</a> mandatory <ins>] <a href="https://drafts.csswg.org/css-values-3/#comb-any">||</a> [ x <a href="https://drafts.csswg.org/css-values-3/#comb-one">|</a> y <a href="https://drafts.csswg.org/css-values-3/#comb-one">|</a> block <a href="https://drafts.csswg.org/css-values-3/#comb-one">|</a> inline <a href="https://drafts.csswg.org/css-values-3/#comb-one">|</a> both ]</ins>
			</table>
		</blockquote>
		<blockquote>
			<p>The scroll-snap-type property defines &hellip; <ins>and which axes are considered</ins>.</p>

			<ins class="block">
				<p>The strictness values (none, proximity, mandatory) specify how strictly snap positions are enforced on the scroll container (by forcing an adjustment to the scroll offset). Values are defined as follows:</p>
			</ins>

			<p>&hellip;</p>

			<ins class="block">
				<p>The axis values specify what axis(es) are affected by <a href="#scroll-snap-position">snap positions</a>,
				and whether <a href="#scroll-snap-position">snap positions</a> are evaluated independently per axis,
				or together as a 2D point.
				Values are defined as follows:
				<dl>
					<dt><dfn class="css" id="valdef-scroll-snap-type-x">x<a class="self-link" href="#valdef-scroll-snap-type-x"></a></dfn>
					<dd> The <a href="https://drafts.csswg.org/css-snappoints-1/#scroll-container">scroll container</a> <a href="#axis-snapping">axis-snaps</a> to <a href="#scroll-snap-position">snap positions</a> in its horizontal axis only.
					<dt><dfn class="css" id="valdef-scroll-snap-type-y">y<a class="self-link" href="#valdef-scroll-snap-type-y"></a></dfn>
					<dd> The <a href="https://drafts.csswg.org/css-snappoints-1/#scroll-container">scroll container</a> <a href="#axis-snapping">axis-snaps</a> to <a href="#scroll-snap-position">snap positions</a> in its vertical axis only.
					<dt><dfn class="css" id="valdef-scroll-snap-type-block">block<a class="self-link" href="#valdef-scroll-snap-type-block"></a></dfn>
					<dd> The <a href="https://drafts.csswg.org/css-snappoints-1/#scroll-container">scroll container</a> <a href="#axis-snapping">axis-snaps</a> to <a href="#scroll-snap-position">snap positions</a> in its block axis only.
					<dt><dfn class="css" id="valdef-scroll-snap-type-inline">inline<a class="self-link" href="#valdef-scroll-snap-type-inline"></a></dfn>
					<dd> The <a href="https://drafts.csswg.org/css-snappoints-1/#scroll-container">scroll container</a> <a href="#axis-snapping">axis-snaps</a> to <a href="#scroll-snap-position">snap positions</a> in its inline axis only.
					<dt><dfn class="css" id="valdef-scroll-snap-type-both">both<a class="self-link" href="#valdef-scroll-snap-type-both"></a></dfn>
					<dd> The <a href="https://drafts.csswg.org/css-snappoints-1/#scroll-container">scroll container</a> <a href="#axis-snapping">axis-snaps</a> to <a href="#scroll-snap-position">snap positions</a> in both of its axises independently
						(potentially snapping to different elements in each axis).
				</dl>
				<p>If no axis value is specified, then the axis is automatically computed:
				<ul>
					<li><p>If the <a href="https://drafts.csswg.org/css-snappoints-1/#scroll-container">scroll container</a> is only scrollable in one axis
						(only one axis has its <a class="property" href="https://drafts.csswg.org/css-overflow-4/#propdef-overflow">overflow</a> set to <a class="css" href="https://drafts.csswg.org/css-overflow-4/#valdef-overflow-auto">auto</a> or <a class="css" href="https://drafts.csswg.org/css-overflow-4/#valdef-overflow-scroll">scroll</a>)
						it <a href="#axis-snapping">axis-snaps</a> in the scrollable axis only.
					<li><p>Otherwise, it <a href="#axis-snapping">axis-snaps</a> in its <a href="https://drafts.csswg.org/css-writing-modes-3/#block-axis">block axis</a> only.
				</ul>
			</ins>
		</blockquote>

		<p>There remains an <a href="https://lists.w3.org/Archives/Public/www-style/2015Nov/0328.html">open issue</a>
		on whether there should be longhands for this and if so, what the shorthand/longhand names should be.

	<dt id=change-trap>Trapping
	 <strong>Merged</strong>
	<dd>
		In Sapporo, the WG <a href="https://www.w3.org/mid/CADhPm3t9Y_L3sUAfmGXbVE7LdgYUcsDXpaRMXfXxxdkpKAtzWw@mail.gmail.com">resolved (27 October 2015)</a>
		to have non-<code>none</code> values of the <code>scroll-snap-type</code> property “trap” descendant scroll snap positions
		in order to provide authors a way of blocking upward propagation of snap positions within a box’s content.
		(<a href="issues-by-issue#issue-82">Issue 82</a> resolved TPAC 2015)

		<p>In order to fix this,
		Tab and I adjusted the definitions of the <code>scroll-snap-type</code> strictness values as follows:

		<blockquote>
			<dl>
				<dt><dfn class="css" id="valdef-scroll-snap-type-none">none</dfn>
				<dd>
					<p><ins>If specified on a <a href="https://drafts.csswg.org/css-snappoints-1/#scroll-container">scroll container</a>,</ins> &hellip;</p>

					<ins class="block"><p>If specified on a non-<a href="https://drafts.csswg.org/css-snappoints-1/#scroll-container">scroll container</a>,
					this value has no effect.</p></ins>

				<dt><dfn class="css" id="valdef-scroll-snap-type-proximity">proximity</dfn>
				<dd>
					<p><ins>If specified on a <a href="https://drafts.csswg.org/css-snappoints-1/#scroll-container">scroll container</a>,</ins> &hellip;</p>

					<ins class="block"><p>If specified on a non-<a href="https://drafts.csswg.org/css-snappoints-1/#scroll-container">scroll container</a>,
					this value “traps” descendant boxes’ <a href="#scroll-snap-position">snap positions</a>,
					preventing them from affecting any ancestor <a href="https://drafts.csswg.org/css-snappoints-1/#scroll-container">scroll containers</a>.</p></ins>

					<p>&hellip;

				<dt><dfn class="css" id="valdef-scroll-snap-type-mandatory">mandatory</dfn>
				<dd>
					<ins>If specified on a <a href="https://drafts.csswg.org/css-snappoints-1/#scroll-container">scroll container</a>,</ins>
					&hellip;

					<ins class="block"><p>If specified on a non-<a href="https://drafts.csswg.org/css-snappoints-1/#scroll-container">scroll container</a>,
					this value “traps” descendant boxes’ <a href="#scroll-snap-position">snap positions</a>,
					preventing them from affecting any ancestor <a href="https://drafts.csswg.org/css-snappoints-1/#scroll-container">scroll containers</a>.</p></ins>

					<p>&hellip;
			</dl>
		</blockquote>

		<p>We also introduced the term “scroll snap container”
		(“snap container” for short)
		to represent the scroll container associated to a particular snap position. This term allows us to give a straightforward definition, in one single place, that accounts for the fact that the relevant box is found along the containing block chain, and also that it is intercepted by any intervening elements with a none-<code>none</code> value for <code>scroll-snap-type</code>.

		<blockquote>
			<p>The <code>scroll-snap-type</code> property specifies <ins>whether a scroll container is a scroll snap container</ins> &hellip;
		</blockquote>

		<blockquote>
			<ins class="block"><p>A box <dfn>captures snap positions</dfn>
			if it is a scroll container <em>or</em> has a value other than <code>none</code> for <code>scroll-snap-type</code>.
			If a box’s nearest snap-position capturing ancestor on its containing block chain is a scroll container with a non-<code>none</code> value for <code>scroll-snap-type</code>,
			then that is the box’s <dfn>scroll snap container</dfn>.
			Otherwise, the box has no scroll snap container,
			and its specified <a>snap positions</a> do not trigger <a>snapping</a>.</p></ins>
		</blockquote>

		<p>This also allows the following fix for some imprecise wording in the definition of <code>scroll-snap-align</code>:

		<blockquote>
			<p>The <code>scroll-snap-align</code> property specifies
			<del>how an element’s scroll snap margin should align with its ancestor scroll container’s snap alignment container</del>
			<ins>the box’s snap position as an alignment of its snap area (as the alignment subject) within its snap container’s snapport (as the alignment container)</ins>.
		</blockquote>

	<dt id=change-rfc2119>RFC2119 Terminology
	<strong>Merged</strong>
	<dd>
		As much as I like the word “guarantee” in the description of <code>mandatory</code>,
		it seems more appropriate to use RFC2119’s “requirement”.

		<blockquote>
			<p>&hellip; the scroll container is <del>guaranteed</del> <ins>required</ins> &hellip;
		</blockquote>

	<dt id=change-warn>Author Warning wrt Mandatory Snapping
	<strong>Merged</strong>
	<dd>
		Based on CSSWG discussions, we added a warning to authors about how despite our best efforts,
		they can still totally screw up the accessibility of the document,
		and should therefore avoid doing that.

		<blockquote>
			<ins class="block"><p><strong class="advisement">Authors should use mandatory snap positions with consideration of
			varyingly-sized screens and (if applicable) varying-sized content.
			In particular, although access to snapped elements larger than the viewport
			is <a href="#snap-overflow">handled by the UA</a>,
			if authors assign mandatory snapping to non-adjacent siblings,
			content in between can become inaccessible
			in cases where it is longer than the screen.</strong>
			<a class="footnote" href="diff#change-warn">7</a></p></ins>
		</blockquote>

	<dt id="change-resnap">Resnapping Requirements
	<dd>
		<ul>
			<li>The first change here is to move the resnapping requirements to the end of the section.
			This is so that this deep technical detail does not get in the way of understanding what,
			overall, the <code>scroll-snap-type</code> values do.
			(This editorial movement is particularly important for authors reading the spec.)
			This also allows us to merge the two paragraphs, which are nearly identical,
			making the spec overall easier to read and less likely to contain inconsistencies.

			<li>As <a href="https://www.w3.org/mid/CADhPm3vtvwTPWfYRWvbb=LePjFJft3JnXLpdTFVO30Muiuxpzg@mail.gmail.com">Resolved 20 January 2016</a>,
			if the content changes,
			and we were either not previously snapped to a snap position
			or that snap position no longer exists,
			the UA must behave as if the user explicitly scrolled to that position,
			i.e. snapping if required.
			The following edits implement this requirement:

			<blockquote>
				<p>If the content changes (e.g. content is added, moved, deleted, resized), the UA must <ins>re-evaluate, and potentially re-snap if necessary, the resulting scroll offset once the positions of the content have restabilized</ins>. &hellip; (stuff about resnapping to the same position) &hellip;  <ins>Otherwise, the scroll container must be re-snapped as if the user had scrolled to its current scroll offset (as an explicit scroll, if no other scroll operation is active).</ins>
			</blockquote>

			<li>Given those changes, and the fact that reachableness of snap positions is handled more generally elsewhere, the following edits clean up the ensuing prose so that the paragraph reads cleanly:

			<blockquote>
				<p>&hellip; If the content changes &hellip;
				<del>such that the scroll container would no longer be snapped to the same snap position it was snapped to before the content change and that same snap position still exists (e.g. its associated element was not deleted) and is reachable, the scroll container must be re-snapped to that same snap position after the content change</del>
				<p>&hellip; If the content changes &hellip;
				changes such that the scroll container would no longer be snapped (e.g. content is added, moved, deleted, resized) to the same snap position it was snapped to before the content change, the scroll container must be re-snapped. If the same snap position it was snapped to before the content change still exists (e.g. its associated element was not deleted) and is reachable, the scroll container must be re-snapped to that same snap position after the content change.
				<p>&hellip; If the content changes (e.g. content is added, moved, deleted, resized), the UA must re-evaluate, and potentially re-snap if necessary, the resulting scroll offset once the positions of the content have restabilized. <ins>However, if there was a previously-snapped snap position (associated with the same element) that still exists after such changes, the UA must remain snapped to it.</ins>
			</blockquote>

			<li>And this last set of insertions add some clarifications.
			<blockquote>
				<p>If the content <ins>or layout of the scroll container</ins> changes e.g. content is added, moved, deleted, resized), the UA must re-evaluate, and potentially re-snap if necessary, the resulting scroll offset once the positions of the content have restabilized. <ins>This can result in no snapping, (e.g. if there are no nearby snap positions for a proximity-snapping scroll container).</ins> However, if there was a previously-snapped snap position (associated with the same element) that still exists after such changes, the UA must remain snapped to it<ins>—even if the changes would have placed a different snap position closer to the current scroll offset</ins>. Otherwise, the scroll container must be re-snapped as if the user had scrolled to its current scroll offset (as an explicit scroll, if no other scroll operation is active).
			</blockquote>
		</ul>

	<dt id=change-relxy>Clarification: Corresponding Dimensions
	<strong>Merged</strong>
	<dd>
		Clarify that percentages are calculated with respect to their corresponding dimensions.
		<blockquote>
			<table class="def">
				<tr>
					<th>Name:
					<td>scroll-snap-padding
				<tr>
					<th>Percentages:</th>
					<td>relative to <ins>the corresponding dimension of</ins> the scroll container’s visual viewport
			</table>
		</blockquote>
	<dt id=change-animatable>Fix Animatable Lines
	<strong>Merged</strong>
	<dd>
		Fix the Animatable lines
		<blockquote>
			<table class="def">
				<tr>
					<th>Name:
					<td>scroll-snap-padding
				<tr>
					<th>Animatable:</th>
					<td><del>yes</del> <ins>as length, percentage, or calc</ins>
			</table>
		</blockquote>
		<blockquote>
			<table class="def">
				<tr>
					<th>Name:
					<td>scroll-snap-margin
				<tr>
					<th>Name:</th>
					<td><del>yes</del> <ins>as length</ins>
			</table>
		</blockquote>


	<dt id=change-length-14>Defining the Scroll Snap Area
	<strong>Merged</strong>
	<dd>
		This wording explicitly hooks into the way <code>margin</code> and <code>border-image-outset</code> are defined,
		which ensures that the assignment of values is fully defined (by reference).
		It also clarifies that the bounding box is axis-aligned <em>in the scroll container’s coordinate space</em>.
		<blockquote>
			<p><ins>The <a class="production css" href="https://drafts.csswg.org/css-values-3/#length-value" title= "Expands to: em | advance measure | ch | vmin | cm | pc | pixel unit | in | rem | q | vh | ex | pt | vw | vmax | mm">&lt;length&gt;</a> values give outsets (interpreted as for <a class="property" href="https://drafts.csswg.org/css2/box.html#propdef-margin">margin</a> or <a class="property" href="https://drafts.csswg.org/css-backgrounds-3/#border-image-outset">border-image-outset</a>).
			The <a href="#scroll-snap-area">scroll snap area</a> is the rectangular bounding box of the transformed border box, plus the specified outsets, axis-aligned in the <a href="https://drafts.csswg.org/css-snappoints-1/#scroll-container">scroll container’s</a> coordinate space.</ins></p>
			<del class="block">
				<dl>
					<dt><dfn class="css" id="valdef-scroll-snap-margin-length1-4"><a class="production css" href="https://drafts.csswg.org/css-values-3/#length-value" title="Expands to: em | advance measure | ch | vmin | cm | pc | pixel unit | in | rem | q | vh | ex | pt | vw | vmax | mm">&lt;length></a>{1,4}<a class="self-link" href="#valdef-scroll-snap-margin-length1-4"></a></dfn>
					<dd>
					Specifies the outset of the element’s snap margin from the axis-aligned bounding box of the transformed border box, in the <a href="#scroll-container">scroll container’s</a> coordinate space.  Outsets are applied to this bounding box, not the border box.
				</dl>
			</del>
		</blockquote>

	<dt id=change-alignment>Definition of <code>scroll-snap-align</code>
	<strong>Merged</strong>
	<dd>
		The following definition is more concise and more concrete,
		because it hooks into the proper terminology.
		<blockquote>
			The <a class="property" href="#propdef-scroll-snap-align">scroll-snap-align</a> property specifies
			<del>how an element’s scroll snap margin should align with its ancestor scroll container’s snapport</del>
			<ins>the box’s <a data-link-type="dfn" href="#scroll-snap-position">snap position</a>
			as an alignment of its <a data-link-type="dfn" href="#scroll-snap-area">snap area</a>
			(as the <a data-link-type="dfn" href="https://drafts.csswg.org/css-align-3/#alignment-subject">alignment subject</a>)
			within its <a data-link-type="dfn" href="#scroll-snap-container">snap container’s</a> <a data-link-type="dfn" href="#scroll-snapport">snapport</a>
			as the <a data-link-type="dfn" href="https://drafts.csswg.org/css-align-3/#alignment-container">alignment container</a>)</ins>.
		</blockquote>

	<dt id=change-align-axes>Alignment Axes
	<dd>
		Tab and I intentionally used the logical axes for <code>scroll-snap-align</code>
		in the proposal we prepared for the WG.
		See <a href="https://lists.w3.org/Archives/Public/www-style/2016Jan/0133.html">further</a> <a href="https://lists.w3.org/Archives/Public/www-style/2016Jan/0138.html">explanation</a>.
		The following changes are due to this difference:
		<blockquote>
			<p>The two values specify the snapping behavior in the <del>x</del> <ins>block</ins> and <del>y</del> <ins>inline</ins> axes, respectively.</p>
		</blockquote>
		<blockquote>
			<ins class="block">
				<p>For all of these values,
				the <a href="https://drafts.csswg.org/css-display-3/#block">block</a> or <a href="https://drafts.csswg.org/css-display-3/#inline">inline</a> axis
				is relative to the element’s parent’s <a href="https://drafts.csswg.org/css-writing-modes-3/#writing-mode">writing mode</a>.</p>
			</ins>
		</blockquote>

<!--
	<dt id=change-valid>Valid snap positions
	<dd>
		We make a distinction between snap positions in general and valid snap positions.
		I can't remember why.
-->

	<dt id=change-subheads>Descriptive Subheadings
	<strong>Merged</strong>
	<dd>
		Tab and I try to use the subheadings as a way of describing what happens,
		preferably using words other than those that appear in the property name itself.
		We feel this helps people find the section they are looking for
		and better understand the concept represented in the section.
		The following changes bring the subheadings in line with this style.
		(We're open to alternative wording.)

		<ul>
			<li><ins>Capturing Scroll Snap Areas:</ins> Properties on the scroll container
			<li>Scroll <del>Snap Types</del> <ins>Snapping Rules</ins>: the <code>scroll-snap-type</code> property
			<li>Scroll <del>Snap Padding</del> <ins>Snapping Window</ins>: the <code>scroll-snap-padding</code> property
			<li><ins>Aligning Scroll Snap Areas:</ins> Properties on the element
			<li>Scroll <del>Snap Margin</del> <ins>Snapping Area</ins>: the <code>scroll-snap-margin</code> property
			<li>Scroll <del>Snap</del> <ins>Snapping</ins> Alignment: the <code>scroll-snap-align</code> property
		</ul>

	<dt id=change-terms>Inlining Definitions
	<strong>Merged</strong>
	<dd>
		While having a glossary appendix is sometimes nice,
		Tab and I tend to put the defining instance of terms inline in the prose:
		either in the prose description of the model,
		or in the description of the property that defines exactly how the term works.
		In some ways this is a stylistic preference, but it has some concrete advantages:
		<ul>
			<li>It keeps normative prose defining a concept all in one place, so that by landing on the term definition it can be understood completely.
			<li>It avoids repetition, and thus the definitions going out-of-sync and conflicting with each other&mdash;as demonstrated here, where the (normative) definition of “snap margin” fails to account for fragmentation or transforms.
		</ul>
		We therefore recommend folding these definitions back into the prose.
		The following changes implement this:

		<ul type=a>
			<li>Shift <code>&lt;dfn></code> markup for “snap position” back to the first paragraph of the overview and delete the (redundant) definition from the definition list:
			<blockquote>
				<p>This module introduces control over <ins class="move">scroll snap positions</ins>, which are scroll positions that produce particular alignments of content within a scrollable viewport. Using the scroll-snap-type property n the relevant scroll container, the author can request a particular bias for the viewport to land on a valid 2 snap position after scrolling operations.
			</blockquote>
			<blockquote>
				<del class="block">
					<dl>
						<dt>snap position
						<dd>For a scroll container, a particular value for its scroll offset is a snap position if when scrolled to that offset the visual viewport of the scroll container would align with a descendent element in the manner specified by the scroll snap properties.
					</dl>
				</del>
			</blockquote>

			<li>Likewise, remove the definitions for the “snap area” and “snapport” and instead make their defining instance the ones in <code>scroll-snap-margin</code> and <code>scroll-snap-padding</code>, respectively:

			<blockquote>
				<del class="block">
					<dl>
						<dt>snap alignment container
						<dd>A scroll container’s snap alignment container is the rectangle obtained by reducing its visual viewport by its scroll-snap-padding. ISSUE: better name for this concept?
						<dt>snap margin
						<dd>An element’s snap margin is the rectangle obtained by expanding its border box by its scroll-snap-margin.
					</dl>
				</del>
			</blockquote>

			<li>Shift the definition of “snapping” up into the Overview:
			<blockquote>
				<ins class="block"><p>The act of adjusting the scroll offset of a scroll container’s visual viewport such that it is aligned to a snap position is called <dfn>snapping</dfn>, and a scroll container is said to be <dfn>snapped</dfn> to a snap position if its visual viewport’s scroll offset is that snap position and there is no active scrolling operation.</p>
			</blockquote>
			<blockquote>
				<del class="block">
					<dl>
						<dt>snapped
						<dd>A scroll container is said to be snapped to a snap position if its visual viewport’s scroll offset is that snap position and there is no active scrolling operation.
						<dt>snap
						<dd>The act of adjusting the scroll offset of a scroll container’s visual viewport such that it is snapped to a snap position is called snapping.
					</dl>
				</del>
			</blockquote>

			<li>Work with editors of <a href="https://www.w3.org/TR/css-overflow-3/">CSS Overflow</a> to define “scroll container” or an equivalent term and link to that. (Currently the ED of CSS Overflow Level 3 defines “scrollable box” as a term. This could be changed to “scroll container” or “scrollable container” if desired.)
		</ul>

		Note: In order to preserve readability of the spec top-to-bottom, we generally provide a parenthetical gloss of a term up front if it is used before its defining instance. In this spec, this is provided in the Overview section:

		<blockquote>
			<p>Snap positions are specified as a particular alignment (scroll-snap-align) of an element’s scroll snap area (its border box, as modified by scroll-snap-margin) within the scroll container’s snapport (its visual viewport, as reduced by scroll-snap-padding). This is conceptually equivalent to specifying the alignment of an alignment subject within an alignment container. A scroll position that satisfies the specified alignment is a valid snap position.</p>
		</blockquote>

	<dt id=change-reword>Rewordings
	<dd>
		The following rewordings are recommended, as they seem somewhat less awkward than the original wording:
		<ul type=a>
			<li><strong>Merged</strong>
				This rewording is less grammatically complex, and maintains parallelism with the previous parenthetical.
				<blockquote>
					<p>Snap positions can be specified as a particular alignment (<code>scroll-snap-align</code>) of an element’s scroll snap area (its border bounding box, as modified by <code>scroll-snap-margin</code>) within the scroll container’s snapport
					(<del>the rectangle obtained by reducing its visual viewport</del> <ins>its visual viewport, as reduced by its scroll-snap-padding</ins>).
				</blockquote>
			<li><strong>Merged</strong>
				This one drops the (in CSS specs) unnecessary “must”,
				and shifts the parenthetical to the end so it doesn't interrupt the connection between the adjective “nearest ancestor” and the noun it describes.
				<blockquote>
					<p><a href="#scroll-snap-position">Snap positions</a> <del>must</del> only affect the nearest ancestor
					<del class="move down">(on the element’s<a href="https://drafts.csswg.org/css-display-3/#containing-block-chain">containing block chain</a>)</del>
					<a href="https://drafts.csswg.org/css-snappoints-1/#scroll-container">scroll container</a>
					<ins class="move up">on the element’s<a href="https://drafts.csswg.org/css-display-3/#containing-block-chain">containing block chain</a></ins>.</p>
				</blockquote>
			<li>
				This rewording maintains parallel structure with the equivalent sentence in the definition for <code>proximity</code> (the concerns about reachability apply to equally to <code>proximity</code>, and are therefore handled in the general requirements for “snap positions”):
				<blockquote>
					<p>the scroll container is
					required
					to be snapped to a valid <a href="#scroll-snap-position">snap position</a> when there are no active scrolling operations.
					<del>If a reachable snap position exists, then the scroll container must snap at the termination of a scroll.</del>
					<ins>That is, it must <a>snap</a> to a valid <a href="#scroll-snap-position">snap position</a> at the termination of a scroll, if any exist.</ins>
				</blockquote>
				Adding parentheses to the following sentence (and simplifying it by using a pronoun) helps the reader to know that this case is considered exceptional:
				<blockquote>
					<p><ins>(</ins>If <del>no reachable snap position</del> <ins>none</ins> exist<del>s</del>, then no snapping occurs.<ins>)</ins></p>
				</blockquote>
			<li><strong>Merged</strong>
				This rewording is more concise, but conveys the same thing.
				<blockquote>
					<p>The <a class="property" href="#propdef-scroll-snap-padding">scroll-snap-padding</a> property defines the <dfn id="scroll-snapport">scroll snapport</dfn>—<!--
					--><del>a region inset from the visual viewport of a <a href="#scroll-container">scroll container</a> used in calculating its <a href="#scroll-snap-position">snap positions</a>.  The snapport is used as the alignment container when calculating <a href="#scroll-snap-position">snap positions</a>.</del>
					<ins>the area of the scrollport that is used as the <a href="https://drafts.csswg.org/css-align-3/#alignment-container">alignment container</a> of the <a href="#scroll-snap-area">scroll snap areas</a> when calculating their <a href="#scroll-snap-position">snap positions</a></ins>.
				</blockquote>
			<li><strong>Merged</strong>
				The definition here is essentially redundant with the previous paragraph;
				Tab and I think this bit of text therefore doesn't need to exist.
				<blockquote>
					<dl>
						<dt><del><dfn class="css" id="valdef-scroll-snap-padding--length--percentage-1-4">[ <a class="production css" href="https://drafts.csswg.org/css-values-3/#length-value" title="Expands to: em | advance measure | ch | vmin | cm | pc | pixel unit | in | rem | q | vh | ex | pt | vw | vmax | mm">&lt;length&gt;</a> | <a class="production css" href="https://drafts.csswg.org/css-values-3/#percentage-value">&lt;percentage&gt;</a> ]{1,4}<a class="self-link" href="#valdef-scroll-snap-padding--length--percentage-1-4"></a></dfn></del>
						<dd><del>Specifies the region inset from the visual viewport.</del> Values are interpreted as for <a class="property" href="https://drafts.csswg.org/css2/box.html#propdef-padding">padding</a>, and specify inward offsets from each edge of the visual viewport.
					</dl>
				</blockquote>
			<li><strong>Merged</strong>
				This rewording is more concise, but conveys the same thing with as much precision.
				<blockquote>
					<p>The <a class="property" href="#propdef-scroll-snap-margin">scroll-snap-margin</a> property
					defines the <dfn id="scroll-snap-area">scroll snap area</dfn>
					<del>on elements within a <a href="#scroll-container">scroll container</a>, used in calculating <a href="#scroll-snap-position">snap positions</a> for that scroll container</del>
					<ins>that is used for snapping this box to the <a href="#scroll-snapport">snapport</a></ins>.
				</blockquote>
			<li><strong>Merged</strong>
				This rewording uses terminology previously defined in order to present more concise definitions with simpler sentence structure:
				<blockquote>
					<p><ins>Values are defined as follows:</ins>
					<dl>
						<dt><dfn class="css" id="valdef-scroll-snap-align-none">none<a class="self-link" href="#valdef-scroll-snap-align-none"></a></dfn>
						</dt><dd>This box does not define a <a href="#scroll-snap-position">snap position</a> in the specified axis.
						</dd><dt><dfn class="css" id="valdef-scroll-snap-align-start">start<a class="self-link" href="#valdef-scroll-snap-align-start"></a></dfn>
						</dt><dd><del class="block">The scroll offset which aligns the start edge of this box’s scroll snap margin with the start edge of its ancestor scroll container’s region defined by <a class="property" href="#propdef-scroll-snap-padding">scroll-snap-padding</a> in the specified axis is a <a href="#scroll-snap-position">snap position</a> in that axis.</del>
						</dd><dd><ins class="block">Start alignment of this box’s <a href="#scroll-snap-area">scroll snap area</a> within the <a href="https://drafts.csswg.org/css-snappoints-1/#scroll-container">scroll container</a>’s <a href="#scroll-snapport">snapport</a> is a valid <a href="#scroll-snap-position">snap position</a> in the specified axis.</ins>
						</dd><dt><dfn class="css" id="valdef-scroll-snap-align-end">end<a class="self-link" href="#valdef-scroll-snap-align-end"></a></dfn>
						</dt><dd><del class="block">The scroll offset which aligns the end edge of this box’s scroll snap margin with the end edge of its ancestor scroll container’s region defined by <a class="property" href="#propdef-scroll-snap-padding">scroll-snap-padding</a> in the specified axis is a <a href="#scroll-snap-position">snap position</a> in that axis.</del>
						</dd><dd><ins class="block">End alignment of this box’s <a href="#scroll-snap-area">scroll snap area</a> within the <a href="https://drafts.csswg.org/css-snappoints-1/#scroll-container">scroll container</a>’s <a href="#scroll-snapport">snapport</a> is a valid <a href="#scroll-snap-position">snap position</a> in the specified axis.</ins>
						</dd><dt><dfn class="css" id="valdef-scroll-snap-align-center">center<a class="self-link" href="#valdef-scroll-snap-align-center"></a></dfn>
						</dt><dd><del class="block">The scroll offset which aligns the center of this box’s scroll snap margin with the center of its ancestor scroll container’s region defined by <a class="property" href="#propdef-scroll-snap-padding">scroll-snap-padding</a> in the specified axis is a <a href="#scroll-snap-position">snap position</a> in that axis.</del>
						</dd><dd><ins class="block">Center alignment of this box’s <a href="#scroll-snap-area">scroll snap area</a> within the <a href="https://drafts.csswg.org/css-snappoints-1/#scroll-container">scroll container</a>’s <a href="#scroll-snapport">snapport</a> is a valid <a href="#scroll-snap-position">snap position</a> in the specified axis.</ins>
					</dl>
				</blockquote>

		</ul>
	<dt id=change-clarify>Clarifying Additions
	<dd>
		The following insertions, we believe, clarify the text:
		<ul type=a>
			<li>Since the model of snap positions is founded on the concept of “valid” and “invalid” scrolled views, this rephrasing helps to explain <code>scroll-snap-type: none</code> in that mental model:
			<blockquote>
				<p>&hellip the scroll container must not snap<ins>: all scroll positions are equally valid</ins>.
			</blockquote>
			<li><strong>Merged</strong>
			This phrase provides something a little more concrete for the reader to relate to, making it less necessary for a casual reader to follow the definition link for “snap” to figure out what that means:
			<blockquote>
				<p>&hellip; the scroll container may snap <ins>to a valid snap position</ins> at the termination of a scroll &hellip;
			</blockquote>
			<blockquote>
				<p>&hellip; the scroll container is guaranteed to be snapped <ins>to a valid snap position</ins> when there are no active scrolling operations &hellip;
			</blockquote>
			<li><strong>Merged</strong>
			This comma breaks up a very long string of (4) prepositional phrases
			by splitting off the UA discretion part:
			<blockquote>
				the scroll container may snap to a valid snap position at the termination of a scroll<ins>,</ins> at the discretion of the UA given the parameters of the scroll.
			</blockquote>
		</ul>
	</dd>

	<dt id=change-point>Point Snapping
	<strong>Merged</strong>
	<dd>
		While Tab and I can accept for point-snapping to be deferred to the next level,
		we would like for at least the next (fully complete) publication
		to include this feature in its definition,
		for archiving (and future discussion).
		Our copy therefore includes definitions for the <code>point</code> value,
		as well as a section about how it works.
		(This is, as you can see, clearly labelled as “to be deferred”, however.)

		<blockquote>
			<table class="def">
				<tr>
					<th>Name:
					<td><dfn>scroll-snap-type</dfn>
				<tr>
					<th>Value
					<td>none <a href="https://drafts.csswg.org/css-values-3/#comb-one">|</a> [ proximity <a href="https://drafts.csswg.org/css-values-3/#comb-one">|</a> mandatory <ins>] <a href="https://drafts.csswg.org/css-values-3/#comb-any">||</a> [ x <a href="https://drafts.csswg.org/css-values-3/#comb-one">|</a> y <a href="https://drafts.csswg.org/css-values-3/#comb-one">|</a> block <a href="https://drafts.csswg.org/css-values-3/#comb-one">|</a> inline <a href="https://drafts.csswg.org/css-values-3/#comb-one">|</a> both <ins><a href="https://drafts.csswg.org/css-values-3/#comb-one">|</a> point</ins> ]
			</table>
		</blockquote>
		<blockquote>
			<ins class="block">
				<dl>
					<dt><dfn class="css" id="valdef-scroll-snap-type-point">point<a class="self-link" href="#valdef-scroll-snap-type-point"></a></dfn>
					<dd> The <a href="https://drafts.csswg.org/css-snappoints-1/#scroll-container">scroll container</a> <a href="#point-snapping">point-snaps</a> to <a href="#scroll-snap-position">snap positions</a> in both axises simultaneously,
					treating each element’s <a href="#scroll-snap-position">snap position</a> as a single 2D position
					(rather than potentially snapping to different elements in each axis).
				</dl>
			</ins>
		</blockquote>
		<blockquote>
			<ins class="block">
				<h3 class="heading settled" data-level="7.2" id="snap-dimensions"><span class="secno">7.2. </span><span class="content">Axis vs Point-Snapping</span><a class="self-link" href="#snap-dimensions"></a></h3>
				<p class="issue" id="issue-323279de"><a class="self-link" href="#issue-323279de"></a> This feature is planned to be removed in the next publication
	in order to reduce the feature-set of Level 1.
	It is included here for future reference in defining Level 2.</p>
				<p>&hellip;</p>
			</ins>
		</blockquote>

		<p>(A likely use case for point snapping is tiled galleries that do not form a strict grid,
		as in <a href="http://labs.jensimmons.com/examples/image-gallery-flexbox-1.html">this example</a> (Flexbox)
		or <a href="http://labs.jensimmons.com/examples/image-gallery-grid-1.html">this one</a> (Grid).
		Again, we're happy to leave this to level 2, but do want the feature design published for future reference.)

	<dt id="change-ack">Acknowledgements Update
	<strong>Merged</strong>
	<dd>
		We've added a list of the people who have contributed the spec,
		and noted that their proposals were mostly accepted rather than mostly ignored.
		<blockquote>
			<p>Many thanks to <del>lots of people for their proposals and recommendations,
			some of which are incorporated into this document.</del>
			<ins>
			David Baron,
			Simon Fraser,
			Håkon Wium Lie,
			Theresa O'Connor,
			François Remy,
			Majid Valpour,
			potentially some anonymous Microsoft engineers (?),
			and most especially to Robert O'Callahan
			for their proposals and recommendations,
			<strong>which have been incorporated into this document</strong>.</ins>
		</blockquote>
</dl>

<hr>

<blockquote cite="https://lists.w3.org/Archives/Public/www-style/2014Jan/0591.html">
	<p>Anyway, here is some feedback about the new draft. I hope it's not ignored again.
	<address>Robert O'Callahan, www-style, 30 January 2014</address>
</blockquote>
